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Abstract 


This package provides an alternative to TikZ’ /tikz/double option, avoiding 
some shortcomings of the original approach. Further features include options to 
draw triple, quadruple, and n-fold paths as well as macros to offset arbitrary paths. 


Compatibility 


This package has been tested with pdflatex, lualatex, xelatex, and plain pdftex. 


1 Quick start 


Add 
\usetikzlibrary{nfold} 


to your preamble. Now you can add /tikz/nfold to any path that uses /tikz/double. 
Be sure to specify /tikz/double distance before /tikz/nfold, as otherwise the latter 
will not be applied. 


\begin{tikzpicture} 


double: \draw[double distance=3pt] 
- ae (0,2) tof[out=0, in=180] (3,3); 
\draw[double distance=3pt, nfold] 
(0,0) tofout=0, in=180] (3,1); 


nfold: \node [right] at (0,3) {double:}; 
\node[right] at (0,1) {nfold:}; 
4 \end{tikzpicture} 


While it appears that adding nfold does not do much here, it avoids some rendering issues 
of /tikz/double, hence I recommend using it in most cases (see Section 2 for details). 
Specify a number for n-fold lines: 


\begin{tikzpicture} 
\draw[double distance=7pt, nfold=5] 
(0,0) tof[out=0, in=180] (3,1) -- (3,0); 
\end{tikzpicture} 


All arrow tips are supported, and there is special treatment for the Implies tip: 


\begin{tikzpicture} 


a \draw[double distance=7pt, nfold=5, 
arrows={Bar [width=18pt]-Implies [red] }] 
(0,1.5) tolbend left] (3,1.5); 


mp=—\ \draw[double distance=7pt, nfold=5, arrows=Implies-Implies] 
(0,0) to[bend left] (3,0); 


\end{tikzpicture} 


Use /tikz/scaling nfold to preserve the distance between component lines instead of 
the overall width of the arrow: 


S \begin{tikzpicture} 
\draw[double equal sign distance, nfold, 
arrows=-Implies] (0,.75) -- (3,.75); 
\draw[double equal sign distance, scaling nfold=4, 
arrows=-Implies] (0,0) -- (3,0); 
\draw[double equal sign distance, scaling nfold=6, 
arrows=-Implies] (0,-1) -- (8,-1); 
\end{tikzpicture} 


Different line joins are supported: 


\begin{tikzpicture}[line join=bevel] 
\draw[line join=miter, double distance=7pt, nfold=4] 
©@,2) == G, 2) = C,2.5)e 
\draw[double distance=7pt, nfold=4] 
@,i1)) == Gi, i) == Gl, i1.5)s 
\draw[line join=round, double distance=7pt, nfold=4] 
(,0) == Gl, ©) = (1,5): 
\end{tikzpicture} 


LEE 


There is also support for tikz-cd with custom label positions for scaling nfold: 


ZA \begin{tikzcd} 
a b a \ar[r, Mapsto, bend left, scaling nfold=3] & 
alja b \ar[d, Rightarrow, nfold, "\alpha", "\beta"’] \\ 
c \ar[r, Mapsfrom, scaling nfold=4, "\gamma" near end] & 
d d 


A 
—— 
\end{tikzcd} 


2 Comparison to /tikz/double 


This package does not aim to supersede /tikz/double, as both the original and the 
nfold approach have their own strengths and weaknesses. The main difference is that 
/tikz/double achieves its goal by drawing the original path twice, once very thick with 
the foreground colour and then slightly less thick with the background colour. By contrast, 
nfold offsets the path: 


/tikz/double: a = 
(1) 
/tikz/nfold: + _ = 2 


While the approach of /tikz/double is very robust and efficient, it does have a few 
pitfalls: 


e Different types of visual glitches can occur in PDF renderers: 


— One common issue is that the white foreground piece completely covers the 
black background piece at certain zoom levels, leading to the top or bottom 
part of the doubled path missing (depending on your PDF viewer and zoom 
level, this issue might be visible in Eq. (1)). 


— Another common glitch is the appearance of a thin horizontal line at the start 
and end of the doubled path (visible in most examples of curved paths if your 
viewer has this problem). The reason is that the larger black path in the 
background is not perfectly covered by the smaller white foreground piece, 
most likely due to rounding errors. 


e The approach assumes that the background has a uniform colour, and it is the user’s 
responsibility to correctly set the background colour: 


\begin{tikzpicture} 
double: \draw[red, line width=1pt] (2.5, 3.3) -- (2.5, 0); 
\draw[line width=2pt, double distance=3pt] 
(0,2) to[out=0, in=180] (3,3); 
\node[right] at (0,3) {double:}; 
\draw[line width=2pt, double distance=3pt, nfold] 
(0,0) to[out=0, in=180] (3,1); 
\node[right] at (0,1) {nfold:}; 
\end{tikzpicture} 


e ‘Transparency does not work correctly: 


\begin{tikzpicture}[line width=1pt] 


double: \draw[double distance=3pt, opacity=.5] 
(0,2) to[out=0, in=180] (3,3); 


\draw[double distance=3pt, opacity=.5, nfold] 
(0,0) tof[out=0, in=180] (3,1); 
\node[right] at (0,3) {double:}; 


suolkty \node[right] at (0,1) {nfold:}; 
\end{tikzpicture} 


e Triple and n-fold paths are not supported (although this could be implemented in 
principle). 


However, there are still situations where /tikz/nfold struggles and /tikz/doubl1le is the 
only viable option, which will be discussed in the next section. 


3 Known issues 


This package is by no means perfect, and even if it were, there would still be some cases 
where the approach of /tikz/double is better suited. The known issues are roughly 
sorted into those that can be fixed in principle and the fundamental limitations of this 
approach. If you find any bugs not listed here, please report them here. 


3.1 


3.2 


Fixable / wish list 


nfold is significantly slower than /tikz/double. Part of the reason is that the 
construction is far more complex, but the code is also far from fully optimised. 


Some rare cases of curves are not offset correctly. The reasons for that are discussed 
below in Appendix A.4. Usually, slightly changing the control points or values of 
the curve will fix the problem. If you find any, please open an issue. 


Closed paths can glitch slightly when the final segment is very short and has non- 
zero angles on both ends. 


Impossible or very hard to fix 


Self-intersecting paths do not have the expected intersections: 


Apabie \begin{tikzpicture} 
ees \draw[double distance=5pt, line width=1pt] 


| | | (©,2.5) —= G1,2.5) Cl,8) == Gl,2) 
| | | (2,2) -- (3,2) rectangle (4,3); 
| \node[right] at (0,3.5) {double:}; 


nfold: \draw[double distance=5pt, line width=1pt, nfold] 
Ope = Cle) Gla) = Gi) 


(2,0) -- (3,0) rectangle (4,1); 
\node[right] at (0,1.5) {nfold:}; 
\end{tikzpicture} 


nfold struggles with high curvatures and wide paths: Let «(t) be the curvature of 
the path in a given point, and let double distance = a. If K(t) > = (ie. the 
radius of the osculating circle is smaller than half the width of the path) for some 


0<t< 1, the output of nfold will not be correct: 


Hei ie \begin{tikzpicture} 
ie \draw[double distance=5pt, line width=1pt] 


ene (0,2) .. controls (4,2) and (0,3) .. (3,2.5); 
\node[right] at (0,3) {double:}; 
\draw[double distance=5pt, line width=1pt, nfold] 
aoe (0,0) .. controls (4,0) and (0,1) .. (3,.5); 


\node[right] at (0,1) {nfold:}; 
a \end{tikzpicture} 


Some, but not all of these cases raise warnings (this feature is on the wish list). This 
is one of the cases where using /tikz/double is the only viable option. 


Dashed paths with significant curvature will desynchronise: 


pases. \begin{tikzpicture} 
= \draw[arrows=-Implies, double equal sign distance, dashed, 
scaling nfold=4] (0,0) to[out=30, in=150] (2,0); 
\end{tikzpicture} 


Curves of nfold slightly deviate from the curves of /tikz/double near joins with 
a non-zero angle: 


A 


This 


\begin{tikzpicture}[line width=1pt] 
\draw[red, double distance=20pt] 
(0,2) -- (2,2) to [out=-90, in=0] (.5,.5); 
\draw[blue, double distance=20pt, opacity=.5, nfold] 


double nfold 


(0,2) -- (2,2) to [out=-90, in=0] (.5,.5); 
y \node[right, red] at (0,3) {double}; 
\node[left, blue] at (3, 3) {nfold}; 
\end{tikzpicture} 


This cannot be fixed without extensive use of the intersections library, hurting 
the performance, and the result might still not look great for orders > 3. 


Very short curves with large angles at the ends result in a glitched output: 


\begin{tikzpicture}[line join=round] 
\draw[black] (1,0) -- (3,0) -- (1.5,1.2) -- (3.8,0.85); 
\draw[red, line width=1ipt, double distance=.7cm, nfold] 
G0) == @,0) = C1.5, 1.2) = @.8,0.85) s 
\draw[blue, double distance=.7cm, nfold] (1,0) -- (3,0) 
to[relative, out=1, in=179] (1.5, 1.2) -- (3.8,0.85); 
\end{tikzpicture} 


This issue has been fixed for straight lines in version 0.1.0 (note how the red line 
is offset correctly), but it is much harder to fix for curves. 


Changing joins in \pgfsys@beginscope without an accompanying TRX group may 
cause inconsistent behaviour in the joins: 


\nakeatletter 
\begin{tikzpicture}[line join=miter, line width=2pt] 
\pgfsys@beginscope 
\pgfsetroundjoin 
\pgfsys@endscope 
\draw[double distance=5pt, nfold] (0,0) -- (.5,2) -- (1,0); 
\end{tikzpicture} 
\nakeatother 


This example has round joins on the large path but miter joins on the constituent 
paths. This problem does not occur with \pgfscope. 


The basic layer pgf commands 


package contains three pgf libraries building upon one another: bezieroffset, 


offsetpath, and nfold. All of these are contained in the 7%kZ library nfold. 


4.1 


Offsetting curves 


This library provides some basic layer commands for offsetting curves and straight lines. 


Use 


\usepgflibrary{bezieroffset} 


to only import this base layer library. The following commands are provided: 


e \pgfoffsetcurve{pti}{pt2}{pt3} {pt4} {distance} 
This macro draws the parallel of a Bézier curve. The first four parameters are the 
control points of the Bézier curve (e.g. in the form of \pgfpoint{}{}), the fifth pa- 
rameter is the distance by which the curve should be offset. A negative value offsets 
the curve in the opposite direction. This macro begins with a \pgfpointmoveto to 
the offset of ptt. 


e \pgfoffsetcurvenomove{pti}{pt2}{pt3}{pt4} {distance} 
The only difference to the previous macro is that this version does not move to the 
offset of pt1. This is useful if one wants to offset an uninterrupted path consisting 
of several curves. The output will only be correct if the previous \pgfpath... call 
ends on the offset of ptt. 


e \pgfoffsetline{pti}{pt2}{distance} 
This macro offsets a straight line. It takes two points and the distance as parameters, 
and starts by moving to the offset of the first point. 


e \pgfoffsetlinenomove{pt1i}{pt2}{distance} 
This macro is analogous to \pgfoffsetcurvenomove. 


4.2 Offsetting paths 
The following macros are part of the pef library offsetpath and offset the whole softpath. 


e \pgfoffsetpath{softpath}{distance} 
This macro offsets softpath by distance. The latter may be negative. 


e \pgfoffsetpathfraction{softpath}{hwidth}{fraction} 
This macro offsets softpath by fraction*hwidth. Note that this is not equivalent 
to the previous macro with length=fraction*hwidth because the joins are treated 
differently, as can be seen in the examples below. Further note that hwidth must 
not be negative, and that fraction=0 does not reproduce the input path. 


e \pgfoffsetpathgfraction{softpath}{hwidth}{fraction} 
This macro is a quicker version of the previous macro does not parse the input values 
using the pgfmath-engine. 


e \pgfoffsetpathindex{softpath}{width}{i}{n} 
In this convenience method, i and n are integers with 1 <2z< n. It calls the 
previous macro with fraction=-1.0 for i=1 and with fraction=1.0 for i=n, hence 
it is capable of reproducing the output of /tikz/nfold=n (albeit in a less efficient 
way). 


In the following example we see how \pgfoffsetpath{..}{Opt} reproduces the input 
path (rendered in black) and how \pgfoffsetpathfraction{. .}{8pt}{0} differs. 


\begin{tikzpicture}[line join=bevel] 
\path[save path=\savedpath] (0,0) -- (1,0) 
tolout=0, in=-80] (1,3) -- (3,2); 
\draw[color=lightgray,line width=16pt,use path=\savedpath] ; 
\pgfoffsetpathfraction{\savedpath}{8pt}{0} 
\pgfsetlinewidth{1pt} \color{red} \pgfusepathqstroke 
\pgfoffsetpath{\savedpath}{8pt} 
\color{blue} \pgfusepathqstroke 
\pgfoffsetpath{\savedpath}{-8pt} 
\color{green} \pgfusepathqstroke 
\pgfoffsetpath{\savedpath}{Opt} 
\pgfsetlinewidth{.4pt} \color{black} \pgfusepathqstroke 
\end{tikzpicture} 


oa) 


Here we see how the commands can be used to customise n-fold paths: 


\begin{tikzpicture} 

\path[save path=\mypath] (0,0) -- (2,0) arc(-90:90:1) 
to[out=180, in=0] (0,1) -- (0,2); 

\foreach \mycolor [count=\i] in {red,green,blue,violet} 
\pgfoffsetpathindex{\mypath}{6pt}{\i}{4} 
\color{\mycolor} \pgfusepathqstroke; 

\end{tikzpicture} 


5 Version history 


e v1.0.0: Restructure and bug fixes 
e v0.1.3: Bug fixes 
e v0.1.2: Bug fixes 
e v0.1.1: Closing paths and structural changes 
— Support for closed paths (cycle and \pgfpathclose) 
— Significant performance improvements due to structural changes 
— Minor bug fixes and optimisations 
e v0.1.0: Major overhaul 
— Support for arbitrary arrow tips 


— Support for directly offsetting soft paths 


New key /tikz/scaling nfold 

— The decorations library was dropped 

— Various performance improvements in bezieroffset (thanks to Qrrbrbirlbel) 
— Very short lines with large angles were fixed (e.g. in tikzcd with squiggly) 
— Numerous bugs fixed 


e v0.0.1: First public version 


A The Bézier offsetting algorithm 


This algorithm is based on an algorithm by Pomax. See A Primer on Bézier curves, the 
source code can be found here. 


A.1 Simple and fully simple Bézier curves 


Throughout this section the term “Bézier curve” refers to a cubic Bézier curve, which is 
defined by four points (A, Az, A3, A1). 


As explained in the aforementioned source, in almost all cases the parallel of a Bézier 
curve is not exactly a Bézier curve itself. To approximate the parallel using Bézier curves, 
we therefore first divide the given curve into “simple” segments which can be offset with 
reasonable accuracy. The following defines a simple segment: 


Definition A.1. A Bézier curve (Aj, Ao, A3, Aq) is simple if 
1. the points Ag and A3 lie on the same side of the line A, Ag, 


2. the absolute angle between the tangents in A; and Ay is at most 7/3 (i.e. the cosine 
is no smaller than 0.5), and 


3. the distances fulfil A, Ap» + A3A4 < Ay Ag? 


Definition A.2. A Bézier curve (Aj, Az, A3, A1) is fully simple? if all of its segments are 
simple in the sense of Definition A.1. 


In order to offset an arbitrary Bézier curve we split it into fully simple segments. 


A.2 Subdivision 


It is well known that at every point 0 < t < 1, de Casteljau’s algorithm can subdivide a 
Bézier curve A = (Aj, Ao, A3, Az) into two Bézier curves B and C (which naturally fulfil 
A; = B, and A, = C,). A more or less heuristic fact is that B and C' are “more likely” 
to be simple than A (if you can prove any of the statements here, please contact me). 
Hence, if one wants to offset a non-simple curve A, one could try to subdivide A until all 
of its segments are simple, then offset each segment. 


!The reference only uses the first two conditions. 
?This terminology is not used in the source. 


A.3  Pomax’ approach 


The original approach by Pomax consists of two passes. The first pass subdivides A on 
all extrema in x or y. In a second pass, each segment A™ is made simple in steps of 
tre t+ 0.01, roughly using the following pseudocode: 


t_1 = t_2 = 0.0 
while t_2 < 1.0: 
S = segment(A from t_1 to t_2+0.01) 
if not isSimple(S): 
segments += [segment(A from t_1 to t_2)] 
t_1l = t_2 
t_2 += 0.01 


Essentially, this ensures with great certainty that the segment is fully simple in the sense 
of Definition A.2. 


The main reason this approach is not used in this library is performance, since the loop is 
quite expensive computationally. Other minor reasons include that the original approach 
is not invariant under reversals or rotations: Reversing and/or rotating a curve yields a 
different subdivision and hence potentially a slightly different-looking curve. 


A.4 The approach used here 
In this library we instead take a recursive approach: 


def makeSimple(A, level): 
if isSimple(A): 
segments. append (A) 
else: 
if level < 0: 
Display a warning 
segments. append (A) 
else: 
first, second = split(A, t=0.5) 
makeSimple(first, level-1) 
makeSimple(second, level-1) 


The default maximum depth is 5, so the curve is split into at most 2° = 32 segments. This 
has the downside that some simple but not fully simple curves may remain undetected and 
be offset slightly incorrectly. If you encounter examples of such curves with bad outputs, 
or if you have any ideas for additional constraints to add to Definition A.1 that can be 
checked with reasonable computational effort, please be in touch. 


A.5 Offsetting simple Bézier curves 


Disregarding edge cases (which will be discussed later), offsetting the curve works as 
follows: 


1. Construct lines orthogonal to the tangent in A; and A, and find their intersection. 
This point is called the origin of the curve, denoted by O. 
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2. The new control points A‘, and Aj, are given by A; and Ay offset orthogonally to 
the tangent. 


3. Construct a ray from A‘ parallel to the tangent in A,;, and construct another ray 
from O through Ay. Now A% is defined to be the intersection of those rays. 


4. A’, can be constructed similarly. 


The construction is shown in the following picture: 


A.6 Removing singularities 


Clearly, as the angle between AA; and AA, decreases, the origin approaches infinity. 
Computing the control points (A‘) by computing the coordinates of O is therefore not 
numerically stable for almost straight curves. However, we can get around this problem 
using elementary geometry. Constructing A and A‘, is independent of the location of the 
origin, so the only difficult part is computing the distances A{A, and A5A‘,. We find 


ae Fae ee 1 
AA, _ OAL _ | | @ =% AA, = A, Ag (1 +d- ) (2) 
A, Ao» OA, OA, OAs 


which is regular as O approaches infinity. Now we to determine the inverse of OA,, which 
can be computed using the law of sines: 


sin(}—a@)  sinfa+ 8) _ sin(} — 8B) 1 1 sin(a + 8) 


oe (3) 
OA, A, Ay, OA, OA, A, Ay cos(/3) 


Note that —% < 8 < % (and hence cos(3) > $) is guaranteed if the curve is simple — in 
fact, simplicity guarantees a- 6 > 0 and |a| + |8| < 3. Using the sine addition theorem 


we can further rewrite the fraction to 


sin(a + 8) sin() 
cos(3) os(B) ’ 


and all of these terms can be computed directly from dot and cross products of vectors 
between the original control points. To summarise, let vj; := A;A;, and let vo, v; be the 
normalised tangents at t = 0 and t = 1, respectively (see Appendix A.8 how they are 
computed). Then 


= sin(a) + cos(a) 


(4) 


es d es = see ye id 
Aj Ag = Ay Ag + = (i X Uj4 — V12° Via = . (5) 


1A4 Via + ty 


Let furthermore tj; := v;;/|U;;| be the normalised vectors. Then we find 


Arar d Ua X ty 
— - a ae 
Ay Ay = AyAg + Vi2 X Uj4 — ViQ*° Uj4—— ] , 
A, A, U4 + ty 


ae d Ua X to 
7 > > > > 
Ai, Ag = AsA3 + U43 X Uj4 — V43° Ul4—— > ] - 
A, A, U14° to 


A.7 Edge cases 
A.7.1 Overlaps: A; = Aj+1 


If there is one overlap A; = Ag, Ag = Az or A3 = Ay, the cubic Bézier curve reduces to a 
quadratic one. For two overlaps, we get a linear Bézier curve (i.e. a straight line), and for 
three overlaps we get a point. The main problem to watch out for is that the tangents to 
and ¢; need to be computed differently: 


e If Ay F Ag, we find to = ty. 
e If Ay = Ay # Ag, we find ty = t3.° 
e If Ay = Ap = A3 # Ag, we find to = ta. 


e If Ay = Ag = A3 = Ag, the curve is just a point and the tangent is not defined. The 
implementation defaults to ty = (1,0). 


The analogous statement hold for t;. In practice we test for approximate, not exact 
equality. 
A.7.2  Overlaps A; = A4 


Equation (6) has one remaining singularity, namely for A; = Ay. This singularity is fun- 
damental and not an artefact: As A, approaches A, while A; A», and A3Ay, stay constant, 


3This implicitly assumes a regular reparametrisation of the curve (e.g. a parametrisation over arc 
length); the usual parametrisation has a gradient of zero at t = 0. 
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aa .-> 
O also approaches Ay, hence the angle between A;A,g and OA, approaches zero, sending 


the intersection point Aj to infinity. 
A closer inspection of this special case reveals a number of sub-cases: 


e Fully degenerate curves with A; ~ Ap ® A3 & Ay. Offsetting these curves in a 
stable manner is impossible, as the gradient and hence the direction in which to 
offset is numerically unstable. Rendering such curves will hardly have any output 
at all anyway. See below in Appendix A.8 how this case is handled. 


e Non-trivial loops with A; Az >> A;Ay and/or A3Aq > Ai Aa, al + |B] = F. Such 
curves violate the second and third condition of Definition A.1, for example: 


Ay Ay 


e Curves with A; Az >> A;Ay and/or A3A4 > Ai Aa, |a|+|8] < 3: Such curves violate 
the third condition of Definition A.1, for example: 


0 A; Ag 


A.8 Stabilising the offsetting algorithm for non-simple curves 


As seen in Appendix A.4, there are cases where the offsetting algorithm will be called 
on non-simple curves. In such cases it is essential that the code does not crash (e.g. 
from division by zero), and that the output produced is at least somewhat sensible. The 
following measures are taken: 


e If A, Ay is very close to zero, we set A‘,AS = A,Ao and AA), = A3A4, forming 
a rather rough approximation of the parallel curve. This causes a warning to be 
logged. 


e For simple curves we find t4- 34 > 0.5 in the denominator. Therefore, for non- 
simple curves, the denominator is clamped to [0.5, 1.0], preventing division by zero. 


4Clamping the fraction d/A;A4 to some maximum value did not work well, as it had a tendency of 
producing false positives. 
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